Nonlinear filtering
===================

.. index:: filtering

When a DSGE model is solved with a higher-order perturbation (or otherwise has
a nonlinear state-space representation), the regime-switching Kalman/Hamilton
filter of :doc:`Linear filtering` no longer applies. RISE then uses a
**sigma-point** filter for regime-switching nonlinear state-space models,
following :cite:`BM2015`.

When the nonlinear filter is used
---------------------------------

``filter`` (and, through it, ``estimate``, ``forecast`` with conditioning, the
historical decomposition, ...) picks the algorithm automatically from the
solution:

- ``solve_order == 1`` -- the linear regime-switching Kalman/Hamilton filter
  (a fast constant-parameter variant when there is a single regime, no
  occasionally-binding constraint, and no real-time information);
- ``solve_order >= 2`` -- a nonlinear sigma-point filter (the default is the
  *switching divided-difference filter*).

Nonlinear filtering with real-time information is not supported (RISE raises an
error).

Choosing the filter
-------------------

Three sigma-point filters are available; the divided-difference filter is the
default, the other two are selected by passing them as the filtering algorithm
via ``kf_user_algo`` (they all share the standard filter signature, so they can
be plugged in directly)::

	% default: switching divided-difference filter
	[fkst, LogLik] = filter(m);

	% switching unscented Kalman filter
	[fkst, LogLik] = filter(m, 'kf_user_algo', 'switching_unscented_kalman_filter');

	% switching cubature Kalman filter
	[fkst, LogLik] = filter(m, 'kf_user_algo', 'switching_cubature_kalman_filter');

The same option can be passed to ``estimate`` (it changes which filter computes
the likelihood that is maximised).

Options
-------

The filtering options apply equally to the linear and nonlinear cases (see
:doc:`Linear filtering` and ``help dsge/filter``); the ones most relevant here:

- ``kf_filtering_level`` ``[0|1|2|{3}]`` -- ``0`` likelihood only; ``1`` + the
  filtered (one-step-ahead) series; ``2`` + the updated series; ``3`` + the
  smoothed series.
- ``kf_ergodic`` ``[{true}|false]``, ``kf_init_variance``, ``kf_user_init`` --
  how the state and regime probabilities are initialised.
- ``kf_presample`` ``[{0}|integer]`` -- observations to discard before
  evaluating the likelihood.
- ``kf_householder_chol`` ``[{false}|true]`` -- return the Cholesky factor when
  taking the Householder transformation; primarily used by the
  divided-difference filter.

User-defined nonlinear filter
-----------------------------

A filter of your own can be supplied through ``kf_user_algo`` -- a function (or
function name, or cell ``{name, extra-args...}``) with signature
``[LogLik, Incr, retcode, Filters] = myFilter(syst, y, U, z, options)``. If it
needs information beyond what RISE passes, prefix the name with ``*`` so RISE
first calls it as ``myFilter(modelObject, struct)`` to let it fetch what it
needs. See :doc:`../Extending DSGE`.

The available sigma-point filters
---------------------------------

.. index:: switching_divided_difference_filter

Switching divided-difference filter
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. include:: switching_divided_difference_filter.rst

.. index:: switching_unscented_kalman_filter

Switching unscented Kalman filter
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. include:: switching_unscented_kalman_filter.rst

.. index:: switching_cubature_kalman_filter

Switching cubature Kalman filter
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. include:: switching_cubature_kalman_filter.rst